/**************************************************************
 * fetchlyric.h - interface to lyric search plugins
 * Copyright (c) 2009  Qin Xiaoxue  <crs.chin@gmail.com>
 *
 * This file is  free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
**************************************************************/


#ifndef __FETCHLYRIC_H
#define __FETCHLYRIC_H 1

#include <stdio.h>
#include <glib.h>


struct lyric_url;

struct fetchlyric_plugin{
  /* 
   *new lyriclist will be appended to @list, if this method is
   *implemented, the @fetchlyric_get_from_url and
   *@fetchlyric_free_list _MUST_ also be implemented.
   */
  GSList   *(*fetchlyric_get_list)(struct fetchlyric_plugin *plugin, const gchar *title, const gchar *artist);

  /* 
   *fetch the lyric file from the url of struct lyric_url of GSList
   *returned by fetchlyric_get_list
   */
  FILE      *(*fetchlyric_get_from_url)(struct fetchlyric_plugin *plugin, struct lyric_url *url);

  /*
   *free and remove element in @list returned by this plugin, other
   *elements are leave untouched and returned.
   */
  GSList    *(*fetchlyric_free_list)(struct fetchlyric_plugin *plugin, GSList *list);





  /* this method _MUST_ be implemented by plugins */
  FILE     *(*fetchlyric_get)(struct fetchlyric_plugin *plugin, const gchar *title, const gchar *artist);

  void         (*clearerr)(struct fetchlyric_plugin *plugin);
  gboolean     (*is_error)(struct fetchlyric_plugin *plugin);
  const gchar *(*strerror)(struct fetchlyric_plugin *plugin);

  void *data;
};


/* struct to export for every plugin */
struct fetchlyric_plugin_descrip{
  struct fetchlyric_plugin  *(*init)(int argc, char **argv);
  void                       (*exit)(struct fetchlyric_plugin *plugin);

  const gchar *name;
  const gchar *description;
  const gchar *author;
  const gchar *mail;
  const gchar *version;
  const gboolean islocal;
};


/* 
 *GSList data field returned by @fetchlyric_get_list
 */
struct lyric_url{
  const gchar *title;
  const gchar *artist;
  const gchar *album;
  struct fetchlyric_plugin *plugin;
  void *url;
};


#define FETCHLYRIC_EXPORT_SYMBOL plugin_descrip
#define FETCHLYRIC_EXPORT_SYMBOL_NAME "plugin_descrip"



struct __fetchlyric;

typedef struct  __fetchlyric fetchlyric_t;

/* all three funtions below:
 *    if @fl is not NULL, it will be taken an object already containning
 * loaded plugins, new plugins will be added to it if not exists, if
 * @plugindir is NULL, sys default dir will be used.*/

/* return FALSE on parameter error or no plugins available in @*fl  */
gboolean fetch_lyric_load_all(fetchlyric_t **fl, const gchar *plugindir, int argc, char **argv);
/* return FALSE on parameter error or the specific plugin cannt be loaded */
gboolean fetch_lyric_load_plugin(fetchlyric_t **fl, const gchar *plugin, const gchar *plugindir, int argc, char **argv);
/* ditto */
gboolean fetch_lyric_load_plugin_from_file(fetchlyric_t **fl, const gchar *path, int argc, char **argv);

struct fetchlyric_plugin_descrip *fetch_lyric_get_descrip(fetchlyric_t *fl, const gchar *plugin);
struct fetchlyric_plugin         *fetch_lyric_get_plugin(fetchlyric_t *fl, const gchar *plugin);

FILE *fetch_lyric_file(fetchlyric_t *fl, const gchar *title, const gchar *artist);
FILE *fetch_lyric_file_from(fetchlyric_t *fl, const gchar *plugin, const gchar *title, const gchar *artist);


GSList *fetch_lyric_get_list(fetchlyric_t *fl, const gchar *title, const gchar *artist);
GSList *fetch_lyric_get_list_from(fetchlyric_t *fl, const gchar *plugin, const gchar *title, const gchar *artist);

FILE   *fetch_lyric_file_next(GSList *list);
FILE   *fetch_lyric_file_next_r(GSList *list, GSList **restore);
gboolean fetch_lyric_free_list(GSList *list);

/* @fl may not contain any plugins any more, but not freed */
gboolean fetch_lyric_unload_plugin(fetchlyric_t *fl, const gchar *plugin);
/* what ever, @fl will be freed , plugins willbe unloaded*/
void     fetch_lyric_unload_all(fetchlyric_t **fl);


gchar **fetch_lyric_plugin_list(fetchlyric_t *fl);
gchar **plugin_list(const gchar *plugindir);

#endif /* __FETCHLYRIC_H */

